home *** CD-ROM | disk | FTP | other *** search
/ Scene Storm / Scene Storm - Volume 1.iso / coding / c / pdc / ccx / ccx.doc < prev    next >
Encoding:
Text File  |  1990-04-19  |  10.8 KB  |  228 lines
  1.  
  2. ccx.doc    [latest change - 15 March 89 by LDH]
  3.  
  4. ABSTRACT
  5.  
  6.     ccx is a smart front end that recognizes the type of file from
  7. the suffix, and will invoke the necessary programs for you to produce an
  8. executable module.  With ccx you can in one command preprocess the source
  9. code, compile the result to assembler, assemble and link the resulting
  10. object module with a set of libraries.
  11.  
  12.  
  13. SYNOPSIS
  14.  
  15.     ccx is a UNIX-like cc command that makes the usual compile,
  16. assemble and link stages a little friendlier.  For example, a runnable
  17. version of the "hello world" program called hello, whose source code is in
  18. a file called hello.c as shown below:
  19.  
  20.     /*hello.c*/
  21.     main()
  22.     {
  23.           printf("Hello World!\n");
  24.     }
  25.  
  26. could be made by typing the following at the CLI prompt:
  27.  
  28.     ccx hello.c
  29.  
  30. ccx would automatically perform the following for you:
  31.  
  32.     o invoke the PDC C compiler on the program.
  33.     o invoke the A68k assembler on the source code put out by PDC.
  34.     o invoke Blink to link the output of A68k with acrt0.o and
  35.           the libraries specified in the PDCLibs environment variable.
  36.     o The executable program will be called hello, and any
  37.       intermediate files will be cleaned up.
  38.  
  39. COMMAND LINE OPTIONS:
  40.  
  41.   ccx supports several command line options which can modify ccx's
  42. behavior,  change where certain files are searched for,  and define where
  43. temporary files are kept during compilation.  Options come in two flavors,
  44. switches and as parameters that take arguments.
  45.  
  46.   Switches appear by themselves on the line preceded by a minus sign.  "-S",
  47. and "-c" are two valid switch options.  It should be noted that upper and
  48. lower case letters are distinct.  "-A" and "-a" for example represent
  49. different switch options.  Furthermore, some options can have special
  50. meanings depending upon whether the flag is "-" or "+".  An example of
  51. such a "sign dependency" is the I option, which adds a directory to search
  52. for include files.  "-I vd0:include" indicates to search vd0:include BEFORE
  53. searching any of the default directories.  "+I vd0:include", conversely,
  54. searches vd0:include AFTER the default directories.  
  55.  
  56.   Parameter options are followed by an additional value optionally separated
  57. by a space.  For example, "-Idf0:include"  and "-I df0:include" are both
  58. valid parameter options.  Here is the current list of options:
  59.  
  60.         -a      Preserve .s files.  The normal behavior of ccx is to delete
  61.                 these intermediate files after running the assembler.  When
  62.                 this option is specified or implied, the compiler places its
  63.                 output in the current directory (rather than on the "quad
  64.                 device") and it is not deleted after the assembler is
  65.                 finished.
  66.  
  67.     -A    Instruct the compiler to annotate its assembly language output
  68.                 with the C source to show how each statement was compiled.
  69.                 Obviously, one would expect the annotated source to not be
  70.                 deleted automatically, so the "-A" option implies "-a" as well.
  71.  
  72.         -c      Suppress the link phase.  All C and assembly programs are 
  73.                 converted to object modules, but not linked together. 
  74.  
  75.     -D    Used to define a macro variable just as though it had
  76.         been included in the source file.  For example, the
  77.         option "-D DEBUG=1" is identical to including the 
  78.         statement #define DEBUG 1 in your C source code.
  79.  
  80.         There are three macro variables that are predefined for
  81.         you:  "amiga", "m68000", and "pdc".  These variables are 
  82.                 useful for writing compiler-specific code in your programs.
  83.  
  84.         -g      Generate debugging information.  Currently, this is 
  85.                 implemented in the form of A68k's "-d" flag.  This approach
  86.                 will give a symbolic debugger access to the global symbol
  87.                 table that is generated during assembly.  It isn't an
  88.                 especially powerful solution, but is adequate in many
  89.                 situations.
  90.  
  91.     -I    Defines additional directories where #include'd files should
  92.     +I    be sought.  For example, "-I dh0:include" would add the 
  93.                 directory include on drive dh0: as the first place to look 
  94.                 for include files.  Additional [+-]I <file> options may be 
  95.                 added, with virtually no limitations.
  96.  
  97.     -l    Defines additional libraries where Blink should look for
  98.     +l    library modules to include in the link list.  If "-lmath"
  99.         were specified, ccx would look for a module math.lib.
  100.                 Note that the ".lib" extension is optional and will be tacked 
  101.                 on if ommitted.
  102.  
  103.         -m      Instructs the linker to produce a link map named <file>.map
  104.                 where <file> is the name of the executable it generates.
  105.  
  106.     -o    Use "-o <name>" to choose the name of the output of the
  107.                 final phase.  Usually this is the output of the linker, though
  108.                 it is interpreted for the resulting object file when used
  109.                 in conjunction with the "-c" option or the assembly file when
  110.                 used with the "-S" option.  The "-o" option presupposes that
  111.                 running ccx will, in the end, only produce one file.  
  112.                 Otherwise, the target of the "-o" option would be ambiguous.
  113.  
  114.         -O      Is swallowed by ccx for compatibility purposes, but is not
  115.                 acted upon in any way.
  116.  
  117.     -q    By default, intermediate assembly language files will be kept
  118.                 in the directory indicated by the "PDCTmpArea" environment
  119.                 variable (if it is not set, then the default becomes "RAM:").
  120.                 Use the "-q <dir>" option to over-ride this by keeping these 
  121.                 intermediate files in <dir>.  This option is particularly 
  122.                 appropriate when trying to compile on a system with limited 
  123.                 memory.  See also the description of the PDCTmpArea environment
  124.                 variable.
  125.  
  126.     -S    Only the compiler is invoked.  No files are assembled.
  127.  
  128.         -s      Used as "-s <object file>" in order to substitute a different
  129.                 startup module during the link phase.  Additionally, "-s 0"
  130.                 will entirely suppress the inclusion of a startup module.
  131.  
  132.         -U      Undefine symbol after preprocessing has completed.  Currently
  133.                 not supported at PDC's command line level.
  134.  
  135.     -V    Prints out the command line passed to all programs
  136.         just before they are invoked.
  137.  
  138.         -W      Sends a string as a command line argument to the specified
  139.                 phase, as in: "-W<phase> <string>" where phase is a char
  140.                 representing:
  141.                                p=preprocessor    0|c=compiler
  142.                                a=assembler    l=linker
  143.  
  144.                 For instance, "-Wc -b" would send a "-b" flag to the compiler,
  145.                 telling it to generate inline assembly for certain select
  146.                 library functions.  Only one "-W" option can be stored for each
  147.                 phase.  The final "-W" for each phase is the one that is used.
  148.                 Quotes can be used to send multiple switches to a phase, as in:
  149.  
  150.                               PDC -c -W0 "-b -P main.pre -g" main.c
  151.  
  152.                 That would send the compiler its -b and -g flags, and also
  153.                 tell it to read from the precompiled header file "main.pre".
  154.  
  155.         -w      Tells Blink to link with a particular file.  This could be used
  156.                 as in "-w project.lnk" to utilize a link file that might have
  157.                 been included with the source to a program.
  158.  
  159.         -Y      This is a quick way to change the name of a program used for
  160.                 one of the phases without recompiling ccx.  "-Yl klink" for
  161.                 instance, would substitute klink for blink as the default
  162.                 linker.  "-Y" without a <phase> specifier implies "-Yp Cpp"
  163.                 and is used to request use of the external preprocessor "Cpp".
  164.  
  165. DEFAULTS:
  166.  
  167. The following extensions have special meaning to ccx:
  168.  
  169.     .c    A C source code file like hello.c above.
  170.     .s    An assembler source code file.
  171.     .a        "         ".
  172.     .asm        "         ".
  173.     .o    An object file, the output of an assembler.
  174.     .obj        "       ".
  175.  
  176. Ccx will obey the search path for the CLI process from which it was run.
  177. Additionally, it accesses the following environment variables for default
  178. parameters:
  179.  
  180. PDCLibs   - Selects a list of standard libraries in the order with which
  181.           they are to be linked.  A typical arrangement could be set by
  182.           placing the following line in your Startup-Sequence:
  183.  
  184.           SetEnv PDCLibs "PDC.lib; Amiga.lib; Math.lib"
  185.  
  186.           There is one important point to bear in mind:  The order in
  187.           which you specify the libraries to link can be CRITICAL.  For
  188.           instance, Math.lib and PDC.lib both contain the function 
  189.           "printf()".  The PDC.lib printf() will print garbage if you
  190.           give it a floating point parameter to print, whereas the Math.lib
  191.           printf() will greatly increase the size of your code because it
  192.           must bring in a number of additional floating point functions.  The
  193.           standard configuration (above) will give you garbage if you try
  194.           printing out a float (try running the fahr.c program after linking
  195.           with libraries in the above order).  One way to alter the ordering
  196.           without changing the PDCLibs environment variable is to use the +l
  197.           and -l options.  "ccx -lmath fahr.c" will make the linker see the
  198.           floating point printf() first and link with that instead.
  199.  
  200. PDCLibDirs - Presents the standard path to search for libraries and
  201.           object modules.  Here's a typical assignment for someone who
  202.           keeps libraries around in "vd0:":
  203.  
  204.           SetEnv PDCLibDirs "pdc:lib; vd0:lib"
  205.  
  206. PDCIncDirs - This is the standard list of places to search for include
  207.           files.  To this list, additional directories can be pre- or appended
  208.           using the [+-]I option.  Again, a typical assignment might go like:
  209.  
  210.           SetEnv PDCIncDirs "pdc:include; vd0:include"
  211.  
  212. Note that with the three environment variables listed above, the order in
  213. which their elements are listed is significant.  For instance, placing
  214. Math.lib before PDC.lib would give you the floating point (read: larger)
  215. versions of f/s/printf() and f/s/scanf() rather than the default versions
  216. in PDC.lib.
  217.  
  218. PDCStartup - Normally "acrt0.o" by default within ccx, you can set this
  219.           environment variable in order to choose some other startup as
  220.           the default.
  221.  
  222. PDCTmpArea - By default, ccx uses "RAM:" as the place to put temporary files.
  223.           If this environment variable is set to a directory, ccx will direct
  224.           temporary files to be placed in that directory.  Note that a trailing
  225.           colon or slash is optional.  Note, however, that assigning PDCTmpArea
  226.           to "t:PDC" does not mean the directory "t:PDC/", but rather prepends
  227.           "t:PDC" to the temporary file name, e.g.: "t:PDChello.s".
  228.